Create a new reader. Sends an invitation to the specified email address.
- 12 May 2026
- 11 Minutes to read
- Contributors
- Print
- DarkLight
Create a new reader. Sends an invitation to the specified email address.
- Updated on 12 May 2026
- 11 Minutes to read
- Contributors
- Print
- DarkLight
Article summary
Did you find this summary helpful?
Thank you for your feedback!
Post
/v3/projects/{project_id}/readers
Creates a new reader account and sends an invitation email to the specified address. The invited_by field is required when authenticating with an M2M (machine-to-machine) token, as the system cannot infer the inviting user from the token. SSO readers can be created by setting is_sso_user to true and providing a scheme_name. Requires the UpdateRolesAccountsAndGroups permission. Related endpoints: GET /v3/projects/{projectId}/readers to list readers, PUT /v3/projects/{projectId}/readers/{readerId} to update a reader.
Security
OAuth
All V3 endpoints require a Bearer token. Generate tokens in the Document360 portal under Settings > API Tokens. Tokens are project-scoped, require the customerApi scope, and do not expire by default. Tokens can be revoked at any time from the portal. Include the token in every request: Authorization: Bearer <your-token>. Alternatively, use the Authorize button below to sign in via OAuth2 Authorization Code flow with PKCE.
FlowAuthorization Code
Authorization URLhttps://identity.document360.net/connect/authorize
Token URLhttps://identity.document360.net/connect/token
Scopes:
customerApiDocument360 Customer API
Path parameters
project_id
string (uuid) Required
The unique identifier of the project. Retrieve project IDs from GET /v3/projects.
Example9a3b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d
Body parameters
Reader creation details.
Invite a reader with project-wide access
Invites a new reader with access to the entire project.
{
"first_name": "John",
"last_name": "Smith",
"email": "[email protected]",
"associated_reader_groups": null,
"access_scope": {
"access_level": "project",
"categories": null,
"project_versions": null,
"languages": null
},
"is_sso_user": false,
"scheme_name": null,
"skip_sso_invitation_email": false,
"invited_by": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d"
}Invite a reader with category-scoped access
Invites a new reader with access restricted to specific categories.
{
"first_name": "Sarah",
"last_name": "Connor",
"email": "[email protected]",
"associated_reader_groups": [
"b2c3d4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e"
],
"access_scope": {
"access_level": "category",
"categories": [
{
"project_version_id": "1c2d3e4f-5a6b-7c8d-9e0f-a1b2c3d4e5f6",
"category_id": "9a3b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d",
"lang_code": "en"
}
],
"project_versions": null,
"languages": null
},
"is_sso_user": false,
"scheme_name": null,
"skip_sso_invitation_email": false,
"invited_by": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d"
}object
Request to invite a new reader to the knowledge base.
first_name
string | null
First name of the reader.
last_name
string | null
Last name of the reader.
email
string (email) Required
Email address of the reader to invite. Must be unique.
Min length1
Example[email protected]
associated_reader_groups
Array of string | null
List of reader group IDs to add this reader to. Retrieve group IDs from GET /v3/projects/{projectId}/readers/groups.
string
access_scope
object | null
The access scope defining which content this reader can view.
access_level
string
The level at which access is scoped. Possible values: 0 = None, 1 = Category, 2 = Version, 3 = Project, 4 = Language, 5 = Article, 6 = Workspace.
Valid values[ "none", "category", "version", "project", "language", "article", "workspace" ]
categories
Array of object (CategoryScope) | null
List of specific category scopes when AccessLevel is Category (1). Null or empty for broader access levels.
object
Specifies access to a specific category within a project version and language.
project_version_id
string | null
Unique identifier of the project version containing the category. Retrieve from GET /v3/projects/{projectId}/project-versions.
category_id
string | null
Unique identifier of the category to grant access to. Retrieve from GET /v3/projects/{projectId}/categories.
lang_code
string | null
Language code for the category translation (e.g., "en", "fr", "de"). Retrieve available languages from GET /v3/projects/{projectId}/languages.
Exampleen
project_versions
Array of string | null
List of project version IDs the reader has access to when AccessLevel is Version (2). Retrieve version IDs from GET /v3/projects/{projectId}/project-versions.
string
languages
Array of object (LanguageScope) | null
List of language scopes defining which translations the reader can access. Applicable when AccessLevel is Language (4).
object
Specifies access to a specific language within a project version.
project_version_id
string | null
Unique identifier of the project version. Retrieve from GET /v3/projects/{projectId}/project-versions.
lang_code
string | null
Language code to grant access to (e.g., "en", "fr", "de"). Retrieve available languages from GET /v3/projects/{projectId}/languages.
Exampleen
is_sso_user
boolean
Whether the reader authenticates via SSO instead of email/password. When true, you must also provide SchemeName. Retrieve available SSO schemes from GET /v3/projects/{projectId}/sso-schemes.
scheme_name
string | null
The SSO scheme name to use. Required when IsSsoUser is true. Retrieve available scheme names from GET /v3/projects/{projectId}/sso-schemes.
skip_sso_invitation_email
boolean
Whether to skip sending the SSO invitation email to the reader.
invited_by
string | null
User ID of the team account member sending the invitation. Required for API token (M2M) authentication. When using a user access token (OAuth), this field is ignored — the user ID is resolved from the token. Retrieve user IDs from GET /v3/projects/{projectId}/users.
Responses
201
Reader created successfully.
Headers
Location
string
URL of the newly created resource.
Newly created reader
Returns the reader that was just created
{
"data": {
"id": "a3b4c5d6-e7f8-4a9b-c0d1-e2f3a4b5c6d7",
"first_name": "Carol",
"last_name": "Smith",
"email": "[email protected]",
"access_scope": {
"access_level": "project",
"categories": [],
"project_versions": [],
"languages": []
},
"associated_reader_groups": [
"b2c3d4e5-f6a7-4b8c-9d0e-a1b2c3d4e5f6"
],
"is_invite_sso_user": false,
"last_login_at": null
},
"success": true,
"request_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"errors": [],
"warnings": []
}object
Generic API response wrapper containing typed data.
data
object
Response data payload.
id
string (uuid) | null
Unique identifier of the reader.
Example9a3b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d
first_name
string | null
First name of the reader.
last_name
string | null
Last name of the reader.
access_scope
object | null
The access scope defining which content this reader can view.
access_level
string
The level at which access is scoped. Possible values: 0 = None, 1 = Category, 2 = Version, 3 = Project, 4 = Language, 5 = Article, 6 = Workspace.
Valid values[ "none", "category", "version", "project", "language", "article", "workspace" ]
categories
Array of object (CategoryScope) | null
List of specific category scopes when AccessLevel is Category (1). Null or empty for broader access levels.
object
Specifies access to a specific category within a project version and language.
project_version_id
string | null
Unique identifier of the project version containing the category. Retrieve from GET /v3/projects/{projectId}/project-versions.
category_id
string | null
Unique identifier of the category to grant access to. Retrieve from GET /v3/projects/{projectId}/categories.
lang_code
string | null
Language code for the category translation (e.g., "en", "fr", "de"). Retrieve available languages from GET /v3/projects/{projectId}/languages.
Exampleen
project_versions
Array of string | null
List of project version IDs the reader has access to when AccessLevel is Version (2). Retrieve version IDs from GET /v3/projects/{projectId}/project-versions.
string
languages
Array of object (LanguageScope) | null
List of language scopes defining which translations the reader can access. Applicable when AccessLevel is Language (4).
object
Specifies access to a specific language within a project version.
project_version_id
string | null
Unique identifier of the project version. Retrieve from GET /v3/projects/{projectId}/project-versions.
lang_code
string | null
Language code to grant access to (e.g., "en", "fr", "de"). Retrieve available languages from GET /v3/projects/{projectId}/languages.
Exampleen
associated_reader_groups
Array of string | null
List of reader group IDs that this reader belongs to. Retrieve group IDs from GET /v3/projects/{projectId}/readers/groups.
string
is_invite_sso_user
boolean
Whether this reader was invited via SSO authentication.
last_login_at
string (date-time) | null
Date and time when the reader last logged in. Null if the reader has never logged in.
success
boolean
Whether the API request was successful.
request_id
string
Unique identifier for request tracing and correlation.
Min length1
errors
Array of object (ApiError) | null
List of errors if the request failed.
object
Represents an error returned by the API.
code
string
Machine-readable error code (e.g. VALIDATION_ERROR, RESOURCE_NOT_FOUND).
Min length1
message
string
Human-readable error message.
Min length1
field
string | null
The request field that caused the error, if applicable.
details
string | null
Additional context about the error.
warnings
Array of object (ApiWarning) | null
List of non-fatal warnings from the request.
object
Represents a non-fatal warning from the API.
code
string
Machine-readable warning code.
Min length1
message
string
Human-readable warning message.
Min length1
400
The request body is malformed or contains invalid JSON.
object
RFC 7807 Problem Details response for V3 API errors. Content-Type: application/problem+json
type
string
URI reference identifying the error type (links to documentation).
Min length1
title
string
Short human-readable summary of the error type.
Min length1
status
integer (int32)
HTTP status code.
detail
string | null
Human-readable explanation specific to this occurrence.
instance
string | null
URI of the request that generated the error.
trace_id
string | null
Request trace identifier for correlation.
errors
Array of object (ApiError) | null
Structured list of specific errors (extension field).
object
Represents an error returned by the API.
code
string
Machine-readable error code (e.g. VALIDATION_ERROR, RESOURCE_NOT_FOUND).
Min length1
message
string
Human-readable error message.
Min length1
field
string | null
The request field that caused the error, if applicable.
details
string | null
Additional context about the error.
warnings
Array of object (ApiWarning) | null
Non-fatal warnings (extension field).
object
Represents a non-fatal warning from the API.
code
string
Machine-readable warning code.
Min length1
message
string
Human-readable warning message.
Min length1
401
Authentication token is missing or invalid.
Headers
WWW-Authenticate
string
Indicates the authentication scheme required. Returns `Bearer` with optional `error` and `error_description` parameters per RFC 6750.
Missing or invalid token
Authentication token is missing or invalid.
{
"type": "https://developer.document360.com/errors/unauthorized",
"title": "Unauthorized.",
"status": 401,
"detail": "The authentication token is missing or has expired.",
"instance": null,
"trace_id": "req_abc123def456",
"errors": [
{
"code": "UNAUTHORIZED",
"message": "Bearer token is missing or invalid.",
"field": null,
"details": null
}
],
"warnings": null
}object
RFC 7807 Problem Details response for V3 API errors. Content-Type: application/problem+json
type
string
URI reference identifying the error type (links to documentation).
Min length1
title
string
Short human-readable summary of the error type.
Min length1
status
integer (int32)
HTTP status code.
detail
string | null
Human-readable explanation specific to this occurrence.
instance
string | null
URI of the request that generated the error.
trace_id
string | null
Request trace identifier for correlation.
errors
Array of object (ApiError) | null
Structured list of specific errors (extension field).
object
Represents an error returned by the API.
code
string
Machine-readable error code (e.g. VALIDATION_ERROR, RESOURCE_NOT_FOUND).
Min length1
message
string
Human-readable error message.
Min length1
field
string | null
The request field that caused the error, if applicable.
details
string | null
Additional context about the error.
warnings
Array of object (ApiWarning) | null
Non-fatal warnings (extension field).
object
Represents a non-fatal warning from the API.
code
string
Machine-readable warning code.
Min length1
message
string
Human-readable warning message.
Min length1
422
Validation failed.
Validation failed
The request body contains invalid data.
{
"type": "https://developer.document360.com/errors/validation-error",
"title": "Unprocessable Entity.",
"status": 422,
"detail": "One or more fields failed validation.",
"instance": null,
"trace_id": "req_abc123def456",
"errors": [
{
"code": "VALIDATION_ERROR",
"message": "This field is required.",
"field": "title",
"details": null
}
],
"warnings": null
}object
RFC 7807 Problem Details response for V3 API errors. Content-Type: application/problem+json
type
string
URI reference identifying the error type (links to documentation).
Min length1
title
string
Short human-readable summary of the error type.
Min length1
status
integer (int32)
HTTP status code.
detail
string | null
Human-readable explanation specific to this occurrence.
instance
string | null
URI of the request that generated the error.
trace_id
string | null
Request trace identifier for correlation.
errors
Array of object (ApiError) | null
Structured list of specific errors (extension field).
object
Represents an error returned by the API.
code
string
Machine-readable error code (e.g. VALIDATION_ERROR, RESOURCE_NOT_FOUND).
Min length1
message
string
Human-readable error message.
Min length1
field
string | null
The request field that caused the error, if applicable.
details
string | null
Additional context about the error.
warnings
Array of object (ApiWarning) | null
Non-fatal warnings (extension field).
object
Represents a non-fatal warning from the API.
code
string
Machine-readable warning code.
Min length1
message
string
Human-readable warning message.
Min length1
429
Rate limit exceeded. Retry after the duration specified in the Retry-After header.
Headers
Retry-After
integer
Number of seconds to wait before retrying the request. Use exponential backoff with jitter for optimal retry behavior.
X-RateLimit-Limit
integer
The maximum number of requests allowed in the current time window. Limits are applied per API token per project.
X-RateLimit-Remaining
integer
The number of requests remaining in the current time window. When this reaches 0, subsequent requests will receive a 429 response.
X-RateLimit-Reset
integer
The UTC epoch timestamp (in seconds) when the current rate limit window resets.
Rate limit exceeded
Rate limit exceeded.
{
"type": "https://developer.document360.com/errors/too-many-requests",
"title": "Too Many Requests.",
"status": 429,
"detail": "Rate limit exceeded. Retry after the duration specified in the Retry-After header.",
"instance": null,
"trace_id": "req_abc123def456",
"errors": [
{
"code": "TOO_MANY_REQUESTS",
"message": "Rate limit exceeded. Retry after the duration specified in the Retry-After header.",
"field": null,
"details": null
}
],
"warnings": null
}object
RFC 7807 Problem Details response for V3 API errors. Content-Type: application/problem+json
type
string
URI reference identifying the error type (links to documentation).
Min length1
title
string
Short human-readable summary of the error type.
Min length1
status
integer (int32)
HTTP status code.
detail
string | null
Human-readable explanation specific to this occurrence.
instance
string | null
URI of the request that generated the error.
trace_id
string | null
Request trace identifier for correlation.
errors
Array of object (ApiError) | null
Structured list of specific errors (extension field).
object
Represents an error returned by the API.
code
string
Machine-readable error code (e.g. VALIDATION_ERROR, RESOURCE_NOT_FOUND).
Min length1
message
string
Human-readable error message.
Min length1
field
string | null
The request field that caused the error, if applicable.
details
string | null
Additional context about the error.
warnings
Array of object (ApiWarning) | null
Non-fatal warnings (extension field).
object
Represents a non-fatal warning from the API.
code
string
Machine-readable warning code.
Min length1
message
string
Human-readable warning message.
Min length1
500
An unexpected server error occurred.
Unexpected server error
Unexpected server error.
{
"type": "https://developer.document360.com/errors/internal-error",
"title": "Internal Server Error.",
"status": 500,
"detail": "An unexpected error occurred. Please try again or contact support.",
"instance": null,
"trace_id": "req_abc123def456",
"errors": [
{
"code": "INTERNAL_SERVER_ERROR",
"message": "An unexpected error occurred.",
"field": null,
"details": null
}
],
"warnings": null
}object
RFC 7807 Problem Details response for V3 API errors. Content-Type: application/problem+json
type
string
URI reference identifying the error type (links to documentation).
Min length1
title
string
Short human-readable summary of the error type.
Min length1
status
integer (int32)
HTTP status code.
detail
string | null
Human-readable explanation specific to this occurrence.
instance
string | null
URI of the request that generated the error.
trace_id
string | null
Request trace identifier for correlation.
errors
Array of object (ApiError) | null
Structured list of specific errors (extension field).
object
Represents an error returned by the API.
code
string
Machine-readable error code (e.g. VALIDATION_ERROR, RESOURCE_NOT_FOUND).
Min length1
message
string
Human-readable error message.
Min length1
field
string | null
The request field that caused the error, if applicable.
details
string | null
Additional context about the error.
warnings
Array of object (ApiWarning) | null
Non-fatal warnings (extension field).
object
Represents a non-fatal warning from the API.
code
string
Machine-readable warning code.
Min length1
message
string
Human-readable warning message.
Min length1
Was this article helpful?
